<!DOCTYPE html>

<html lang="en" data-content_root="./">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Eclipse Paho™ MQTT Python Client &#8212; Eclipse paho-mqtt  documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d1102ebc" />
    <link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=12dfc556" />
    <script src="_static/documentation_options.js?v=5929fcd5"></script>
    <script src="_static/doctools.js?v=9a2dae69"></script>
    <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="client module" href="client.html" />
   
  <link rel="stylesheet" href="_static/custom.css" type="text/css" />
  

  
  

  </head><body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          

          <div class="body" role="main">
            
  <div class="admonition note">
<p class="admonition-title">Note</p>
<p>This is the documentation of the upcoming 2.0 release of paho-mqtt (already
available as pre-release). For 1.6.x release of paho-mqtt, see the
Github README.</p>
</div>
<section id="eclipse-paho-mqtt-python-client">
<h1>Eclipse Paho™ MQTT Python Client<a class="headerlink" href="#eclipse-paho-mqtt-python-client" title="Link to this heading">¶</a></h1>
<p>The <a class="reference external" href="https://eclipse.dev/paho/files/paho.mqtt.python/html/client.html">full documentation is available here</a>.</p>
<p><strong>Warning breaking change</strong> - Release 2.0 contains a breaking change; see the <a class="reference external" href="https://github.com/eclipse-paho/paho.mqtt.python/releases/tag/v2.0.0">release notes</a> and <a class="reference external" href="https://eclipse.dev/paho/files/paho.mqtt.python/html/migrations.html">migration details</a>.</p>
<p>This document describes the source code for the <a class="reference external" href="http://eclipse.org/paho/">Eclipse Paho</a> MQTT Python client library, which implements versions 5.0, 3.1.1, and 3.1 of the MQTT protocol.</p>
<p>This code provides a client class which enables applications to connect to an <a class="reference external" href="http://mqtt.org/">MQTT</a> broker to publish messages, and to subscribe to topics and receive published messages. It also provides some helper functions to make publishing one off messages to an MQTT server very straightforward.</p>
<p>It supports Python 3.7+.</p>
<p>The MQTT protocol is a machine-to-machine (M2M)/”Internet of Things” connectivity protocol. Designed as an extremely lightweight publish/subscribe messaging transport, it is useful for connections with remote locations where a small code footprint is required and/or network bandwidth is at a premium.</p>
<p>Paho is an <a class="reference external" href="https://www.eclipse.org/org/foundation/">Eclipse Foundation</a> project.</p>
<section id="contents">
<h2>Contents<a class="headerlink" href="#contents" title="Link to this heading">¶</a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="#installation">Installation</a></p></li>
<li><p><a class="reference internal" href="#known-limitations">Known limitations</a></p></li>
<li><dl class="simple">
<dt><a class="reference internal" href="#usage-and-api">Usage and API</a></dt><dd><ul>
<li><p><a class="reference internal" href="#getting-started">Getting Started</a></p></li>
<li><dl class="simple">
<dt><a class="reference internal" href="#client">Client</a></dt><dd><ul>
<li><p><a class="reference internal" href="#network-loop">Network loop</a></p></li>
<li><p><a class="reference internal" href="#callbacks">Callbacks</a></p></li>
<li><p><a class="reference internal" href="#logger">Logger</a></p></li>
<li><p><a class="reference internal" href="#external-event-loop-support">External event loop support</a></p></li>
<li><p><a class="reference internal" href="#global-helper-functions">Global helper functions</a></p></li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><a class="reference internal" href="#publish">Publish</a></dt><dd><ul>
<li><p><a class="reference internal" href="#single">Single</a></p></li>
<li><p><a class="reference internal" href="#multiple">Multiple</a></p></li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><a class="reference internal" href="#subscribe">Subscribe</a></dt><dd><ul>
<li><p><a class="reference internal" href="#simple">Simple</a></p></li>
<li><p><a class="reference internal" href="#using-callback">Using Callback</a></p></li>
</ul>
</dd>
</dl>
</li>
</ul>
</dd>
</dl>
</li>
<li><p><a class="reference internal" href="#reporting-bugs">Reporting bugs</a></p></li>
<li><p><a class="reference internal" href="#more-information">More information</a></p></li>
</ul>
</section>
<section id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Link to this heading">¶</a></h2>
<p>The latest stable version is available in the Python Package Index (PyPi) and can be installed using</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">paho</span><span class="o">-</span><span class="n">mqtt</span>
</pre></div>
</div>
<p>Or with <code class="docutils literal notranslate"><span class="pre">virtualenv</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">virtualenv</span> <span class="n">paho</span><span class="o">-</span><span class="n">mqtt</span>
<span class="n">source</span> <span class="n">paho</span><span class="o">-</span><span class="n">mqtt</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">activate</span>
<span class="n">pip</span> <span class="n">install</span> <span class="n">paho</span><span class="o">-</span><span class="n">mqtt</span>
</pre></div>
</div>
<p>To obtain the full code, including examples and tests, you can clone the git repository:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">eclipse</span><span class="o">/</span><span class="n">paho</span><span class="o">.</span><span class="n">mqtt</span><span class="o">.</span><span class="n">python</span>
</pre></div>
</div>
<p>Once you have the code, it can be installed from your repository as well:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">paho</span><span class="o">.</span><span class="n">mqtt</span><span class="o">.</span><span class="n">python</span>
<span class="n">pip</span> <span class="n">install</span> <span class="o">-</span><span class="n">e</span> <span class="o">.</span>
</pre></div>
</div>
<p>To perform all tests (including MQTT v5 tests), you also need to clone paho.mqtt.testing in paho.mqtt.python folder:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">eclipse</span><span class="o">/</span><span class="n">paho</span><span class="o">.</span><span class="n">mqtt</span><span class="o">.</span><span class="n">testing</span><span class="o">.</span><span class="n">git</span>
<span class="n">cd</span> <span class="n">paho</span><span class="o">.</span><span class="n">mqtt</span><span class="o">.</span><span class="n">testing</span>
<span class="n">git</span> <span class="n">checkout</span> <span class="n">a4dc694010217b291ee78ee13a6d1db812f9babd</span>
</pre></div>
</div>
</section>
<section id="known-limitations">
<h2>Known limitations<a class="headerlink" href="#known-limitations" title="Link to this heading">¶</a></h2>
<p>The following are the known unimplemented MQTT features.</p>
<p>When <code class="docutils literal notranslate"><span class="pre">clean_session</span></code> is False, the session is only stored in memory and not persisted. This means that
when the client is restarted (not just reconnected, the object is recreated usually because the
program was restarted) the session is lost. This results in a possible message loss.</p>
<p>The following part of the client session is lost:</p>
<ul>
<li><p>QoS 2 messages which have been received from the server, but have not been completely acknowledged.</p>
<p>Since the client will blindly acknowledge any PUBCOMP (last message of a QoS 2 transaction), it
won’t hang but will lose this QoS 2 message.</p>
</li>
<li><p>QoS 1 and QoS 2 messages which have been sent to the server, but have not been completely acknowledged.</p>
<p>This means that messages passed to <code class="docutils literal notranslate"><span class="pre">publish()</span></code> may be lost. This could be mitigated by taking care
that all messages passed to <code class="docutils literal notranslate"><span class="pre">publish()</span></code> have a corresponding <code class="docutils literal notranslate"><span class="pre">on_publish()</span></code> call or use <a class="reference internal" href="client.html#paho.mqtt.client.MQTTMessageInfo.wait_for_publish" title="paho.mqtt.client.MQTTMessageInfo.wait_for_publish"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">wait_for_publish</span></code></a>.</p>
<p>It also means that the broker may have the QoS2 message in the session. Since the client starts
with an empty session it don’t know it and will reuse the mid. This is not yet fixed.</p>
</li>
</ul>
<p>Also, when <code class="docutils literal notranslate"><span class="pre">clean_session</span></code> is True, this library will republish QoS &gt; 0 message across network
reconnection. This means that QoS &gt; 0 message won’t be lost. But the standard says that
we should discard any message for which the publish packet was sent. Our choice means that
we are not compliant with the standard and it’s possible for QoS 2 to be received twice.</p>
<p>You should set <code class="docutils literal notranslate"><span class="pre">clean_session</span> <span class="pre">=</span> <span class="pre">False</span></code> if you need the QoS 2 guarantee of only one delivery.</p>
</section>
<section id="usage-and-api">
<h2>Usage and API<a class="headerlink" href="#usage-and-api" title="Link to this heading">¶</a></h2>
<p>Detailed API documentation <a class="reference external" href="https://eclipse.dev/paho/files/paho.mqtt.python/html/client.html">is available online</a> or could be built from <code class="docutils literal notranslate"><span class="pre">docs/</span></code> and samples are available in the <a class="reference external" href="https://github.com/eclipse-paho/paho.mqtt.python/tree/master/examples">examples</a> directory.</p>
<p>The package provides two modules, a full <a class="reference internal" href="client.html#paho.mqtt.client.Client" title="paho.mqtt.client.Client"><code class="xref any py py-class docutils literal notranslate"><span class="pre">Client</span></code></a> and few <a class="reference internal" href="helpers.html"><span class="doc">helpers</span></a> for simple publishing or subscribing.</p>
<section id="getting-started">
<h3>Getting Started<a class="headerlink" href="#getting-started" title="Link to this heading">¶</a></h3>
<p>Here is a very simple example that subscribes to the broker $SYS topic tree and prints out the resulting messages:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">paho.mqtt.client</span> <span class="k">as</span> <span class="nn">mqtt</span>

<span class="c1"># The callback for when the client receives a CONNACK response from the server.</span>
<span class="k">def</span> <span class="nf">on_connect</span><span class="p">(</span><span class="n">client</span><span class="p">,</span> <span class="n">userdata</span><span class="p">,</span> <span class="n">flags</span><span class="p">,</span> <span class="n">reason_code</span><span class="p">,</span> <span class="n">properties</span><span class="p">):</span>
    <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Connected with result code </span><span class="si">{</span><span class="n">reason_code</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
    <span class="c1"># Subscribing in on_connect() means that if we lose the connection and</span>
    <span class="c1"># reconnect then subscriptions will be renewed.</span>
    <span class="n">client</span><span class="o">.</span><span class="n">subscribe</span><span class="p">(</span><span class="s2">&quot;$SYS/#&quot;</span><span class="p">)</span>

<span class="c1"># The callback for when a PUBLISH message is received from the server.</span>
<span class="k">def</span> <span class="nf">on_message</span><span class="p">(</span><span class="n">client</span><span class="p">,</span> <span class="n">userdata</span><span class="p">,</span> <span class="n">msg</span><span class="p">):</span>
    <span class="nb">print</span><span class="p">(</span><span class="n">msg</span><span class="o">.</span><span class="n">topic</span><span class="o">+</span><span class="s2">&quot; &quot;</span><span class="o">+</span><span class="nb">str</span><span class="p">(</span><span class="n">msg</span><span class="o">.</span><span class="n">payload</span><span class="p">))</span>

<span class="n">mqttc</span> <span class="o">=</span> <span class="n">mqtt</span><span class="o">.</span><span class="n">Client</span><span class="p">(</span><span class="n">mqtt</span><span class="o">.</span><span class="n">CallbackAPIVersion</span><span class="o">.</span><span class="n">VERSION2</span><span class="p">)</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">on_connect</span> <span class="o">=</span> <span class="n">on_connect</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">on_message</span> <span class="o">=</span> <span class="n">on_message</span>

<span class="n">mqttc</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">&quot;mqtt.eclipseprojects.io&quot;</span><span class="p">,</span> <span class="mi">1883</span><span class="p">,</span> <span class="mi">60</span><span class="p">)</span>

<span class="c1"># Blocking call that processes network traffic, dispatches callbacks and</span>
<span class="c1"># handles reconnecting.</span>
<span class="c1"># Other loop*() functions are available that give a threaded interface and a</span>
<span class="c1"># manual interface.</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">loop_forever</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="client">
<h3>Client<a class="headerlink" href="#client" title="Link to this heading">¶</a></h3>
<p>You can use the client class as an instance, within a class or by subclassing. The general usage flow is as follows:</p>
<ul class="simple">
<li><p>Create a client instance</p></li>
<li><p>Connect to a broker using one of the <code class="docutils literal notranslate"><span class="pre">connect*()</span></code> functions</p></li>
<li><p>Call one of the <code class="docutils literal notranslate"><span class="pre">loop*()</span></code> functions to maintain network traffic flow with the broker</p></li>
<li><p>Use <code class="docutils literal notranslate"><span class="pre">subscribe()</span></code> to subscribe to a topic and receive messages</p></li>
<li><p>Use <code class="docutils literal notranslate"><span class="pre">publish()</span></code> to publish messages to the broker</p></li>
<li><p>Use <code class="docutils literal notranslate"><span class="pre">disconnect()</span></code> to disconnect from the broker</p></li>
</ul>
<p>Callbacks will be called to allow the application to process events as necessary. These callbacks are described below.</p>
<section id="network-loop">
<h4>Network loop<a class="headerlink" href="#network-loop" title="Link to this heading">¶</a></h4>
<p>These functions are the driving force behind the client. If they are not
called, incoming network data will not be processed and outgoing network data
will not be sent. There are four options for managing the
network loop. Three are described here, the fourth in “External event loop
support” below. Do not mix the different loop functions.</p>
<section id="loop-start-loop-stop">
<h5>loop_start() / loop_stop()<a class="headerlink" href="#loop-start-loop-stop" title="Link to this heading">¶</a></h5>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">mqttc</span><span class="o">.</span><span class="n">loop_start</span><span class="p">()</span>

<span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
    <span class="n">temperature</span> <span class="o">=</span> <span class="n">sensor</span><span class="o">.</span><span class="n">blocking_read</span><span class="p">()</span>
    <span class="n">mqttc</span><span class="o">.</span><span class="n">publish</span><span class="p">(</span><span class="s2">&quot;paho/temperature&quot;</span><span class="p">,</span> <span class="n">temperature</span><span class="p">)</span>

<span class="n">mqttc</span><span class="o">.</span><span class="n">loop_stop</span><span class="p">()</span>
</pre></div>
</div>
<p>These functions implement a threaded interface to the network loop. Calling
<a class="reference internal" href="client.html#paho.mqtt.client.Client.loop_start" title="paho.mqtt.client.Client.loop_start"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">loop_start()</span></code></a> once, before or after <code class="docutils literal notranslate"><span class="pre">connect*()</span></code>, runs a thread in the
background to call <a class="reference internal" href="client.html#paho.mqtt.client.Client.loop" title="paho.mqtt.client.Client.loop"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">loop()</span></code></a> automatically. This frees up the main thread for
other work that may be blocking. This call also handles reconnecting to the
broker. Call <a class="reference internal" href="client.html#paho.mqtt.client.Client.loop_stop" title="paho.mqtt.client.Client.loop_stop"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">loop_stop()</span></code></a> to stop the background thread.
The loop is also stopped if you call <a class="reference internal" href="client.html#paho.mqtt.client.Client.disconnect" title="paho.mqtt.client.Client.disconnect"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">disconnect()</span></code></a>.</p>
</section>
<section id="loop-forever">
<h5>loop_forever()<a class="headerlink" href="#loop-forever" title="Link to this heading">¶</a></h5>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">mqttc</span><span class="o">.</span><span class="n">loop_forever</span><span class="p">(</span><span class="n">retry_first_connection</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
</pre></div>
</div>
<p>This is a blocking form of the network loop and will not return until the
client calls <a class="reference internal" href="client.html#paho.mqtt.client.Client.disconnect" title="paho.mqtt.client.Client.disconnect"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">disconnect()</span></code></a>. It automatically handles reconnecting.</p>
<p>Except for the first connection attempt when using <a class="reference internal" href="client.html#paho.mqtt.client.Client.connect_async" title="paho.mqtt.client.Client.connect_async"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">connect_async</span></code></a>, use
<code class="docutils literal notranslate"><span class="pre">retry_first_connection=True</span></code> to make it retry the first connection.</p>
<p><em>Warning</em>: This might lead to situations where the client keeps connecting to an
non existing host without failing.</p>
</section>
<section id="loop">
<h5>loop()<a class="headerlink" href="#loop" title="Link to this heading">¶</a></h5>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">run</span> <span class="o">=</span> <span class="kc">True</span>
<span class="k">while</span> <span class="n">run</span><span class="p">:</span>
    <span class="n">rc</span> <span class="o">=</span> <span class="n">mqttc</span><span class="o">.</span><span class="n">loop</span><span class="p">(</span><span class="n">timeout</span><span class="o">=</span><span class="mf">1.0</span><span class="p">)</span>
    <span class="k">if</span> <span class="n">rc</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">:</span>
        <span class="c1"># need to handle error, possible reconnecting or stopping the application</span>
</pre></div>
</div>
<p>Call regularly to process network events. This call waits in <code class="docutils literal notranslate"><span class="pre">select()</span></code> until
the network socket is available for reading or writing, if appropriate, then
handles the incoming/outgoing data. This function blocks for up to <code class="docutils literal notranslate"><span class="pre">timeout</span></code>
seconds. <code class="docutils literal notranslate"><span class="pre">timeout</span></code> must not exceed the <code class="docutils literal notranslate"><span class="pre">keepalive</span></code> value for the client or
your client will be regularly disconnected by the broker.</p>
<p>Using this kind of loop, require you to handle reconnection strategie.</p>
</section>
</section>
<section id="callbacks">
<h4>Callbacks<a class="headerlink" href="#callbacks" title="Link to this heading">¶</a></h4>
<p>The interface to interact with paho-mqtt include various callback that are called by
the library when some events occur.</p>
<p>The callbacks are functions defined in your code, to implement the require action on those events. This could
be simply printing received message or much more complex behaviour.</p>
<p>Callbacks API is versioned, and the selected version is the <a class="reference internal" href="types.html#paho.mqtt.enums.CallbackAPIVersion" title="paho.mqtt.enums.CallbackAPIVersion"><code class="xref any py py-class docutils literal notranslate"><span class="pre">CallbackAPIVersion</span></code></a> you provided to <a class="reference internal" href="client.html#paho.mqtt.client.Client" title="paho.mqtt.client.Client"><code class="xref any py py-class docutils literal notranslate"><span class="pre">Client</span></code></a>
constructor. Currently two version are supported:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">CallbackAPIVersion.VERSION1</span></code>: it’s the historical version used in paho-mqtt before version 2.0.
It’s the API used before the introduction of <a class="reference internal" href="types.html#paho.mqtt.enums.CallbackAPIVersion" title="paho.mqtt.enums.CallbackAPIVersion"><code class="xref any py py-class docutils literal notranslate"><span class="pre">CallbackAPIVersion</span></code></a>.
This version is deprecated and will be removed in paho-mqtt version 3.0.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CallbackAPIVersion.VERSION2</span></code>: This version is more consistent between protocol MQTT 3.x and MQTT 5.x. It’s also
much more usable with MQTT 5.x since reason code and properties are always provided when available.
It’s recommended for all user to upgrade to this version. It’s highly recommended for MQTT 5.x user.</p></li>
</ul>
<p>The following callbacks exists:</p>
<ul class="simple">
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_connect" title="paho.mqtt.client.Client.on_connect"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_connect()</span></code></a>: called when the CONNACK from the broker is received. The call could be for a refused connection,
check the reason_code to see if the connection is successful or rejected.</p></li>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_connect_fail" title="paho.mqtt.client.Client.on_connect_fail"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_connect_fail()</span></code></a>: called by <a class="reference internal" href="client.html#paho.mqtt.client.Client.loop_forever" title="paho.mqtt.client.Client.loop_forever"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">loop_forever()</span></code></a> and <a class="reference internal" href="client.html#paho.mqtt.client.Client.loop_start" title="paho.mqtt.client.Client.loop_start"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">loop_start()</span></code></a> when the TCP connection failed to establish.
This callback is not called when using <a class="reference internal" href="client.html#paho.mqtt.client.Client.connect" title="paho.mqtt.client.Client.connect"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">connect()</span></code></a> or <a class="reference internal" href="client.html#paho.mqtt.client.Client.reconnect" title="paho.mqtt.client.Client.reconnect"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">reconnect()</span></code></a> directly. It’s only called following
an automatic (re)connection made by <a class="reference internal" href="client.html#paho.mqtt.client.Client.loop_start" title="paho.mqtt.client.Client.loop_start"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">loop_start()</span></code></a> and <a class="reference internal" href="client.html#paho.mqtt.client.Client.loop_forever" title="paho.mqtt.client.Client.loop_forever"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">loop_forever()</span></code></a></p></li>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_disconnect" title="paho.mqtt.client.Client.on_disconnect"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_disconnect()</span></code></a>: called when the connection is closed.</p></li>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_message" title="paho.mqtt.client.Client.on_message"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_message()</span></code></a>: called when a MQTT message is received from the broker.</p></li>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_publish" title="paho.mqtt.client.Client.on_publish"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_publish()</span></code></a>: called when an MQTT message was sent to the broker. Depending on QoS level the callback is called
at different moment:</p>
<ul>
<li><p>For QoS == 0, it’s called as soon as the message is sent over the network. This could be before the corresponding <code class="docutils literal notranslate"><span class="pre">publish()</span></code> return.</p></li>
<li><p>For QoS == 1, it’s called when the corresponding PUBACK is received from the broker</p></li>
<li><p>For QoS == 2, it’s called when the corresponding PUBCOMP is received from the broker</p></li>
</ul>
</li>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_subscribe" title="paho.mqtt.client.Client.on_subscribe"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_subscribe()</span></code></a>: called when the SUBACK is received from the broker</p></li>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_unsubscribe" title="paho.mqtt.client.Client.on_unsubscribe"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_unsubscribe()</span></code></a>: called when the UNSUBACK is received from the broker</p></li>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_log" title="paho.mqtt.client.Client.on_log"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_log()</span></code></a>: called when the library log a message</p></li>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_socket_open" title="paho.mqtt.client.Client.on_socket_open"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_socket_open</span></code></a>, <a class="reference internal" href="client.html#paho.mqtt.client.Client.on_socket_close" title="paho.mqtt.client.Client.on_socket_close"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_socket_close</span></code></a>, <a class="reference internal" href="client.html#paho.mqtt.client.Client.on_socket_register_write" title="paho.mqtt.client.Client.on_socket_register_write"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_socket_register_write</span></code></a>, <a class="reference internal" href="client.html#paho.mqtt.client.Client.on_socket_unregister_write" title="paho.mqtt.client.Client.on_socket_unregister_write"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_socket_unregister_write</span></code></a>: callbacks used for external loop support. See below for details.</p></li>
</ul>
<p>For the signature of each callback, see the <a class="reference external" href="https://eclipse.dev/paho/files/paho.mqtt.python/html/client.html">online documentation</a>.</p>
<section id="subscriber-example">
<h5>Subscriber example<a class="headerlink" href="#subscriber-example" title="Link to this heading">¶</a></h5>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">paho.mqtt.client</span> <span class="k">as</span> <span class="nn">mqtt</span>

<span class="k">def</span> <span class="nf">on_subscribe</span><span class="p">(</span><span class="n">client</span><span class="p">,</span> <span class="n">userdata</span><span class="p">,</span> <span class="n">mid</span><span class="p">,</span> <span class="n">reason_code_list</span><span class="p">,</span> <span class="n">properties</span><span class="p">):</span>
    <span class="c1"># Since we subscribed only for a single channel, reason_code_list contains</span>
    <span class="c1"># a single entry</span>
    <span class="k">if</span> <span class="n">reason_code_list</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">is_failure</span><span class="p">:</span>
        <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Broker rejected you subscription: </span><span class="si">{</span><span class="n">reason_code_list</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Broker granted the following QoS: </span><span class="si">{</span><span class="n">reason_code_list</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">value</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>

<span class="k">def</span> <span class="nf">on_unsubscribe</span><span class="p">(</span><span class="n">client</span><span class="p">,</span> <span class="n">userdata</span><span class="p">,</span> <span class="n">mid</span><span class="p">,</span> <span class="n">reason_code_list</span><span class="p">,</span> <span class="n">properties</span><span class="p">):</span>
    <span class="c1"># Be careful, the reason_code_list is only present in MQTTv5.</span>
    <span class="c1"># In MQTTv3 it will always be empty</span>
    <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">reason_code_list</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span> <span class="ow">or</span> <span class="ow">not</span> <span class="n">reason_code_list</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">is_failure</span><span class="p">:</span>
        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;unsubscribe succeeded (if SUBACK is received in MQTTv3 it success)&quot;</span><span class="p">)</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Broker replied with failure: </span><span class="si">{</span><span class="n">reason_code_list</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
    <span class="n">client</span><span class="o">.</span><span class="n">disconnect</span><span class="p">()</span>

<span class="k">def</span> <span class="nf">on_message</span><span class="p">(</span><span class="n">client</span><span class="p">,</span> <span class="n">userdata</span><span class="p">,</span> <span class="n">message</span><span class="p">):</span>
    <span class="c1"># userdata is the structure we choose to provide, here it&#39;s a list()</span>
    <span class="n">userdata</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">message</span><span class="o">.</span><span class="n">payload</span><span class="p">)</span>
    <span class="c1"># We only want to process 10 messages</span>
    <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">userdata</span><span class="p">)</span> <span class="o">&gt;=</span> <span class="mi">10</span><span class="p">:</span>
        <span class="n">client</span><span class="o">.</span><span class="n">unsubscribe</span><span class="p">(</span><span class="s2">&quot;$SYS/#&quot;</span><span class="p">)</span>

<span class="k">def</span> <span class="nf">on_connect</span><span class="p">(</span><span class="n">client</span><span class="p">,</span> <span class="n">userdata</span><span class="p">,</span> <span class="n">flags</span><span class="p">,</span> <span class="n">reason_code</span><span class="p">,</span> <span class="n">properties</span><span class="p">):</span>
    <span class="k">if</span> <span class="n">reason_code</span><span class="o">.</span><span class="n">is_failure</span><span class="p">:</span>
        <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Failed to connect: </span><span class="si">{</span><span class="n">reason_code</span><span class="si">}</span><span class="s2">. loop_forever() will retry connection&quot;</span><span class="p">)</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="c1"># we should always subscribe from on_connect callback to be sure</span>
        <span class="c1"># our subscribed is persisted across reconnections.</span>
        <span class="n">client</span><span class="o">.</span><span class="n">subscribe</span><span class="p">(</span><span class="s2">&quot;$SYS/#&quot;</span><span class="p">)</span>

<span class="n">mqttc</span> <span class="o">=</span> <span class="n">mqtt</span><span class="o">.</span><span class="n">Client</span><span class="p">(</span><span class="n">mqtt</span><span class="o">.</span><span class="n">CallbackAPIVersion</span><span class="o">.</span><span class="n">VERSION2</span><span class="p">)</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">on_connect</span> <span class="o">=</span> <span class="n">on_connect</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">on_message</span> <span class="o">=</span> <span class="n">on_message</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">on_subscribe</span> <span class="o">=</span> <span class="n">on_subscribe</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">on_unsubscribe</span> <span class="o">=</span> <span class="n">on_unsubscribe</span>

<span class="n">mqttc</span><span class="o">.</span><span class="n">user_data_set</span><span class="p">([])</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">&quot;mqtt.eclipseprojects.io&quot;</span><span class="p">)</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">loop_forever</span><span class="p">()</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Received the following message: </span><span class="si">{</span><span class="n">mqttc</span><span class="o">.</span><span class="n">user_data_get</span><span class="p">()</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="publisher-example">
<h5>publisher example<a class="headerlink" href="#publisher-example" title="Link to this heading">¶</a></h5>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">time</span>
<span class="kn">import</span> <span class="nn">paho.mqtt.client</span> <span class="k">as</span> <span class="nn">mqtt</span>

<span class="k">def</span> <span class="nf">on_publish</span><span class="p">(</span><span class="n">client</span><span class="p">,</span> <span class="n">userdata</span><span class="p">,</span> <span class="n">mid</span><span class="p">,</span> <span class="n">reason_code</span><span class="p">,</span> <span class="n">properties</span><span class="p">):</span>
    <span class="c1"># reason_code and properties will only be present in MQTTv5. It&#39;s always unset in MQTTv3</span>
    <span class="k">try</span><span class="p">:</span>
        <span class="n">userdata</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">mid</span><span class="p">)</span>
    <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;on_publish() is called with a mid not present in unacked_publish&quot;</span><span class="p">)</span>
        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;This is due to an unavoidable race-condition:&quot;</span><span class="p">)</span>
        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;* publish() return the mid of the message sent.&quot;</span><span class="p">)</span>
        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;* mid from publish() is added to unacked_publish by the main thread&quot;</span><span class="p">)</span>
        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;* on_publish() is called by the loop_start thread&quot;</span><span class="p">)</span>
        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;While unlikely (because on_publish() will be called after a network round-trip),&quot;</span><span class="p">)</span>
        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot; this is a race-condition that COULD happen&quot;</span><span class="p">)</span>
        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;&quot;</span><span class="p">)</span>
        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;The best solution to avoid race-condition is using the msg_info from publish()&quot;</span><span class="p">)</span>
        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;We could also try using a list of acknowledged mid rather than removing from pending list,&quot;</span><span class="p">)</span>
        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;but remember that mid could be re-used !&quot;</span><span class="p">)</span>

<span class="n">unacked_publish</span> <span class="o">=</span> <span class="nb">set</span><span class="p">()</span>
<span class="n">mqttc</span> <span class="o">=</span> <span class="n">mqtt</span><span class="o">.</span><span class="n">Client</span><span class="p">(</span><span class="n">mqtt</span><span class="o">.</span><span class="n">CallbackAPIVersion</span><span class="o">.</span><span class="n">VERSION2</span><span class="p">)</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">on_publish</span> <span class="o">=</span> <span class="n">on_publish</span>

<span class="n">mqttc</span><span class="o">.</span><span class="n">user_data_set</span><span class="p">(</span><span class="n">unacked_publish</span><span class="p">)</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">&quot;mqtt.eclipseprojects.io&quot;</span><span class="p">)</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">loop_start</span><span class="p">()</span>

<span class="c1"># Our application produce some messages</span>
<span class="n">msg_info</span> <span class="o">=</span> <span class="n">mqttc</span><span class="o">.</span><span class="n">publish</span><span class="p">(</span><span class="s2">&quot;paho/test/topic&quot;</span><span class="p">,</span> <span class="s2">&quot;my message&quot;</span><span class="p">,</span> <span class="n">qos</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="n">unacked_publish</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">msg_info</span><span class="o">.</span><span class="n">mid</span><span class="p">)</span>

<span class="n">msg_info2</span> <span class="o">=</span> <span class="n">mqttc</span><span class="o">.</span><span class="n">publish</span><span class="p">(</span><span class="s2">&quot;paho/test/topic&quot;</span><span class="p">,</span> <span class="s2">&quot;my message2&quot;</span><span class="p">,</span> <span class="n">qos</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="n">unacked_publish</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">msg_info2</span><span class="o">.</span><span class="n">mid</span><span class="p">)</span>

<span class="c1"># Wait for all message to be published</span>
<span class="k">while</span> <span class="nb">len</span><span class="p">(</span><span class="n">unacked_publish</span><span class="p">):</span>
    <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">0.1</span><span class="p">)</span>

<span class="c1"># Due to race-condition described above, the following way to wait for all publish is safer</span>
<span class="n">msg_info</span><span class="o">.</span><span class="n">wait_for_publish</span><span class="p">()</span>
<span class="n">msg_info2</span><span class="o">.</span><span class="n">wait_for_publish</span><span class="p">()</span>

<span class="n">mqttc</span><span class="o">.</span><span class="n">disconnect</span><span class="p">()</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">loop_stop</span><span class="p">()</span>
</pre></div>
</div>
</section>
</section>
<section id="logger">
<h4>Logger<a class="headerlink" href="#logger" title="Link to this heading">¶</a></h4>
<p>The Client emit some log message that could be useful during troubleshooting. The easiest way to
enable logs is the call <a class="reference internal" href="client.html#paho.mqtt.client.Client.enable_logger" title="paho.mqtt.client.Client.enable_logger"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">enable_logger()</span></code></a>. It’s possible to provide a custom logger or let the
default logger being used.</p>
<p>Example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>
<span class="kn">import</span> <span class="nn">paho.mqtt.client</span> <span class="k">as</span> <span class="nn">mqtt</span>

<span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>

<span class="n">mqttc</span> <span class="o">=</span> <span class="n">mqtt</span><span class="o">.</span><span class="n">Client</span><span class="p">(</span><span class="n">mqtt</span><span class="o">.</span><span class="n">CallbackAPIVersion</span><span class="o">.</span><span class="n">VERSION2</span><span class="p">)</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">enable_logger</span><span class="p">()</span>

<span class="n">mqttc</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">&quot;mqtt.eclipseprojects.io&quot;</span><span class="p">,</span> <span class="mi">1883</span><span class="p">,</span> <span class="mi">60</span><span class="p">)</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">loop_start</span><span class="p">()</span>

<span class="c1"># Do additional action needed, publish, subscribe, ...</span>
<span class="p">[</span><span class="o">...</span><span class="p">]</span>
</pre></div>
</div>
<p>It’s also possible to define a on_log callback that will receive a copy of all log messages. Example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">paho.mqtt.client</span> <span class="k">as</span> <span class="nn">mqtt</span>

<span class="k">def</span> <span class="nf">on_log</span><span class="p">(</span><span class="n">client</span><span class="p">,</span> <span class="n">userdata</span><span class="p">,</span> <span class="n">paho_log_level</span><span class="p">,</span> <span class="n">messages</span><span class="p">):</span>
    <span class="k">if</span> <span class="n">paho_log_level</span> <span class="o">==</span> <span class="n">mqtt</span><span class="o">.</span><span class="n">LogLevel</span><span class="o">.</span><span class="n">MQTT_LOG_ERR</span><span class="p">:</span>
        <span class="nb">print</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>

<span class="n">mqttc</span> <span class="o">=</span> <span class="n">mqtt</span><span class="o">.</span><span class="n">Client</span><span class="p">(</span><span class="n">mqtt</span><span class="o">.</span><span class="n">CallbackAPIVersion</span><span class="o">.</span><span class="n">VERSION2</span><span class="p">)</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">on_log</span> <span class="o">=</span> <span class="n">on_log</span>

<span class="n">mqttc</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">&quot;mqtt.eclipseprojects.io&quot;</span><span class="p">,</span> <span class="mi">1883</span><span class="p">,</span> <span class="mi">60</span><span class="p">)</span>
<span class="n">mqttc</span><span class="o">.</span><span class="n">loop_start</span><span class="p">()</span>

<span class="c1"># Do additional action needed, publish, subscribe, ...</span>
<span class="p">[</span><span class="o">...</span><span class="p">]</span>
</pre></div>
</div>
<p>The correspondence with Paho logging levels and standard ones is the following:</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Paho</p></th>
<th class="head"><p>logging</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">MQTT_LOG_ERR</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">logging.ERROR</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">MQTT_LOG_WARNING</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">logging.WARNING</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">MQTT_LOG_NOTICE</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">logging.INFO</span></code> <em>(no direct equivalent)</em></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">MQTT_LOG_INFO</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">logging.INFO</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">MQTT_LOG_DEBUG</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">logging.DEBUG</span></code></p></td>
</tr>
</tbody>
</table>
</section>
<section id="external-event-loop-support">
<h4>External event loop support<a class="headerlink" href="#external-event-loop-support" title="Link to this heading">¶</a></h4>
<p>To support other network loop like asyncio (see <a class="reference external" href="https://github.com/eclipse-paho/paho.mqtt.python/tree/master/examples">examples</a>), the library expose some
method and callback to support those use-case.</p>
<p>The following loop method exists:</p>
<ul class="simple">
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.loop_read" title="paho.mqtt.client.Client.loop_read"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">loop_read</span></code></a>: should be called when the socket is ready for reading.</p></li>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.loop_write" title="paho.mqtt.client.Client.loop_write"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">loop_write</span></code></a>: should be called when the socket is ready for writing AND the library want to write data.</p></li>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.loop_misc" title="paho.mqtt.client.Client.loop_misc"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">loop_misc</span></code></a>: should be called every few seconds to handle message retrying and pings.</p></li>
</ul>
<p>In pseudo code, it give the following:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">while</span> <span class="n">run</span><span class="p">:</span>
    <span class="k">if</span> <span class="n">need_read</span><span class="p">:</span>
        <span class="n">mqttc</span><span class="o">.</span><span class="n">loop_read</span><span class="p">()</span>
    <span class="k">if</span> <span class="n">need_write</span><span class="p">:</span>
        <span class="n">mqttc</span><span class="o">.</span><span class="n">loop_write</span><span class="p">()</span>
    <span class="n">mqttc</span><span class="o">.</span><span class="n">loop_misc</span><span class="p">()</span>

    <span class="k">if</span> <span class="ow">not</span> <span class="n">need_read</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">need_write</span><span class="p">:</span>
        <span class="c1"># But don&#39;t wait more than few seconds, loop_misc() need to be called regularly</span>
        <span class="n">wait_for_change_in_need_read_or_write</span><span class="p">()</span>
    <span class="n">updated_need_read_and_write</span><span class="p">()</span>
</pre></div>
</div>
<p>The tricky part is implementing the update of need_read / need_write and wait for condition change. To support
this, the following method exists:</p>
<ul>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.socket" title="paho.mqtt.client.Client.socket"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">socket()</span></code></a>: which return the socket object when the TCP connection is open.
This call is particularly useful for <a class="reference external" href="https://docs.python.org/3/library/select.html#select.select">select</a> based loops. See <code class="docutils literal notranslate"><span class="pre">examples/loop_select.py</span></code>.</p></li>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.want_write" title="paho.mqtt.client.Client.want_write"><code class="xref any py py-meth docutils literal notranslate"><span class="pre">want_write()</span></code></a>: return true if there is data  waiting to be written. This is close to the
<code class="docutils literal notranslate"><span class="pre">need_writew</span></code> of above pseudo-code, but you should also check whether the socket is ready for writing.</p></li>
<li><p>callbacks <code class="docutils literal notranslate"><span class="pre">on_socket_*</span></code>:</p>
<blockquote>
<div><ul class="simple">
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_socket_open" title="paho.mqtt.client.Client.on_socket_open"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_socket_open</span></code></a>: called when the socket is opened.</p></li>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_socket_close" title="paho.mqtt.client.Client.on_socket_close"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_socket_close</span></code></a>: called when the socket is about to be closed.</p></li>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_socket_register_write" title="paho.mqtt.client.Client.on_socket_register_write"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_socket_register_write</span></code></a>: called when there is data the client want to write on the socket</p></li>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_socket_unregister_write" title="paho.mqtt.client.Client.on_socket_unregister_write"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_socket_unregister_write</span></code></a>: called when there is no more data to write on the socket.</p></li>
</ul>
</div></blockquote>
<p>Callbacks are particularly useful for event loops where you register or unregister a socket
for reading+writing. See <code class="docutils literal notranslate"><span class="pre">examples/loop_asyncio.py</span></code> for an example.</p>
</li>
</ul>
<p>The callbacks are always called in this order:</p>
<ul class="simple">
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_socket_open" title="paho.mqtt.client.Client.on_socket_open"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_socket_open</span></code></a></p></li>
<li><p>Zero or more times:</p>
<ul>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_socket_register_write" title="paho.mqtt.client.Client.on_socket_register_write"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_socket_register_write</span></code></a></p></li>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_socket_unregister_write" title="paho.mqtt.client.Client.on_socket_unregister_write"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_socket_unregister_write</span></code></a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="client.html#paho.mqtt.client.Client.on_socket_close" title="paho.mqtt.client.Client.on_socket_close"><code class="xref any py py-attr docutils literal notranslate"><span class="pre">on_socket_close</span></code></a></p></li>
</ul>
</section>
<section id="global-helper-functions">
<h4>Global helper functions<a class="headerlink" href="#global-helper-functions" title="Link to this heading">¶</a></h4>
<p>The client module also offers some global helper functions.</p>
<p><code class="docutils literal notranslate"><span class="pre">topic_matches_sub(sub,</span> <span class="pre">topic)</span></code> can be used to check whether a <code class="docutils literal notranslate"><span class="pre">topic</span></code>
matches a <code class="docutils literal notranslate"><span class="pre">subscription</span></code>.</p>
<p>For example:</p>
<blockquote>
<div><p>the topic <code class="docutils literal notranslate"><span class="pre">foo/bar</span></code> would match the subscription <code class="docutils literal notranslate"><span class="pre">foo/#</span></code> or <code class="docutils literal notranslate"><span class="pre">+/bar</span></code></p>
<p>the topic <code class="docutils literal notranslate"><span class="pre">non/matching</span></code> would not match the subscription <code class="docutils literal notranslate"><span class="pre">non/+/+</span></code></p>
</div></blockquote>
</section>
</section>
<section id="publish">
<h3>Publish<a class="headerlink" href="#publish" title="Link to this heading">¶</a></h3>
<p>This module provides some helper functions to allow straightforward publishing
of messages in a one-shot manner. In other words, they are useful for the
situation where you have a single/multiple messages you want to publish to a
broker, then disconnect with nothing else required.</p>
<p>The two functions provided are <a class="reference internal" href="helpers.html#paho.mqtt.publish.single" title="paho.mqtt.publish.single"><code class="xref any py py-func docutils literal notranslate"><span class="pre">single()</span></code></a> and <a class="reference internal" href="helpers.html#paho.mqtt.publish.multiple" title="paho.mqtt.publish.multiple"><code class="xref any py py-func docutils literal notranslate"><span class="pre">multiple()</span></code></a>.</p>
<p>Both functions include support for MQTT v5.0, but do not currently let you
set any properties on connection or when sending messages.</p>
<section id="single">
<h4>Single<a class="headerlink" href="#single" title="Link to this heading">¶</a></h4>
<p>Publish a single message to a broker, then disconnect cleanly.</p>
<p>Example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">paho.mqtt.publish</span> <span class="k">as</span> <span class="nn">publish</span>

<span class="n">publish</span><span class="o">.</span><span class="n">single</span><span class="p">(</span><span class="s2">&quot;paho/test/topic&quot;</span><span class="p">,</span> <span class="s2">&quot;payload&quot;</span><span class="p">,</span> <span class="n">hostname</span><span class="o">=</span><span class="s2">&quot;mqtt.eclipseprojects.io&quot;</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="multiple">
<h4>Multiple<a class="headerlink" href="#multiple" title="Link to this heading">¶</a></h4>
<p>Publish multiple messages to a broker, then disconnect cleanly.</p>
<p>Example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">paho.mqtt.enums</span> <span class="kn">import</span> <span class="n">MQTTProtocolVersion</span>
<span class="kn">import</span> <span class="nn">paho.mqtt.publish</span> <span class="k">as</span> <span class="nn">publish</span>

<span class="n">msgs</span> <span class="o">=</span> <span class="p">[{</span><span class="s1">&#39;topic&#39;</span><span class="p">:</span><span class="s2">&quot;paho/test/topic&quot;</span><span class="p">,</span> <span class="s1">&#39;payload&#39;</span><span class="p">:</span><span class="s2">&quot;multiple 1&quot;</span><span class="p">},</span>
    <span class="p">(</span><span class="s2">&quot;paho/test/topic&quot;</span><span class="p">,</span> <span class="s2">&quot;multiple 2&quot;</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="kc">False</span><span class="p">)]</span>
<span class="n">publish</span><span class="o">.</span><span class="n">multiple</span><span class="p">(</span><span class="n">msgs</span><span class="p">,</span> <span class="n">hostname</span><span class="o">=</span><span class="s2">&quot;mqtt.eclipseprojects.io&quot;</span><span class="p">,</span> <span class="n">protocol</span><span class="o">=</span><span class="n">MQTTProtocolVersion</span><span class="o">.</span><span class="n">MQTTv5</span><span class="p">)</span>
</pre></div>
</div>
</section>
</section>
<section id="subscribe">
<h3>Subscribe<a class="headerlink" href="#subscribe" title="Link to this heading">¶</a></h3>
<p>This module provides some helper functions to allow straightforward subscribing
and processing of messages.</p>
<p>The two functions provided are <a class="reference internal" href="helpers.html#paho.mqtt.subscribe.simple" title="paho.mqtt.subscribe.simple"><code class="xref any py py-func docutils literal notranslate"><span class="pre">simple()</span></code></a> and <a class="reference internal" href="helpers.html#paho.mqtt.subscribe.callback" title="paho.mqtt.subscribe.callback"><code class="xref any py py-func docutils literal notranslate"><span class="pre">callback()</span></code></a>.</p>
<p>Both functions include support for MQTT v5.0, but do not currently let you
set any properties on connection or when subscribing.</p>
<section id="simple">
<h4>Simple<a class="headerlink" href="#simple" title="Link to this heading">¶</a></h4>
<p>Subscribe to a set of topics and return the messages received. This is a
blocking function.</p>
<p>Example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">paho.mqtt.subscribe</span> <span class="k">as</span> <span class="nn">subscribe</span>

<span class="n">msg</span> <span class="o">=</span> <span class="n">subscribe</span><span class="o">.</span><span class="n">simple</span><span class="p">(</span><span class="s2">&quot;paho/test/topic&quot;</span><span class="p">,</span> <span class="n">hostname</span><span class="o">=</span><span class="s2">&quot;mqtt.eclipseprojects.io&quot;</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;</span><span class="si">%s</span><span class="s2"> </span><span class="si">%s</span><span class="s2">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">msg</span><span class="o">.</span><span class="n">topic</span><span class="p">,</span> <span class="n">msg</span><span class="o">.</span><span class="n">payload</span><span class="p">))</span>
</pre></div>
</div>
</section>
<section id="using-callback">
<h4>Using Callback<a class="headerlink" href="#using-callback" title="Link to this heading">¶</a></h4>
<p>Subscribe to a set of topics and process the messages received using a user
provided callback.</p>
<p>Example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">paho.mqtt.subscribe</span> <span class="k">as</span> <span class="nn">subscribe</span>

<span class="k">def</span> <span class="nf">on_message_print</span><span class="p">(</span><span class="n">client</span><span class="p">,</span> <span class="n">userdata</span><span class="p">,</span> <span class="n">message</span><span class="p">):</span>
    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;</span><span class="si">%s</span><span class="s2"> </span><span class="si">%s</span><span class="s2">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">message</span><span class="o">.</span><span class="n">topic</span><span class="p">,</span> <span class="n">message</span><span class="o">.</span><span class="n">payload</span><span class="p">))</span>
    <span class="n">userdata</span><span class="p">[</span><span class="s2">&quot;message_count&quot;</span><span class="p">]</span> <span class="o">+=</span> <span class="mi">1</span>
    <span class="k">if</span> <span class="n">userdata</span><span class="p">[</span><span class="s2">&quot;message_count&quot;</span><span class="p">]</span> <span class="o">&gt;=</span> <span class="mi">5</span><span class="p">:</span>
        <span class="c1"># it&#39;s possible to stop the program by disconnecting</span>
        <span class="n">client</span><span class="o">.</span><span class="n">disconnect</span><span class="p">()</span>

<span class="n">subscribe</span><span class="o">.</span><span class="n">callback</span><span class="p">(</span><span class="n">on_message_print</span><span class="p">,</span> <span class="s2">&quot;paho/test/topic&quot;</span><span class="p">,</span> <span class="n">hostname</span><span class="o">=</span><span class="s2">&quot;mqtt.eclipseprojects.io&quot;</span><span class="p">,</span> <span class="n">userdata</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;message_count&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">})</span>
</pre></div>
</div>
</section>
</section>
</section>
<section id="reporting-bugs">
<h2>Reporting bugs<a class="headerlink" href="#reporting-bugs" title="Link to this heading">¶</a></h2>
<p>Please report bugs in the issues tracker at <a class="reference external" href="https://github.com/eclipse-paho/paho.mqtt.python/issues">https://github.com/eclipse/paho.mqtt.python/issues</a>.</p>
</section>
<section id="more-information">
<h2>More information<a class="headerlink" href="#more-information" title="Link to this heading">¶</a></h2>
<p>Discussion of the Paho clients takes place on the <a class="reference external" href="https://dev.eclipse.org/mailman/listinfo/paho-dev">Eclipse paho-dev mailing list</a>.</p>
<p>General questions about the MQTT protocol itself (not this library) are discussed in the <a class="reference external" href="https://groups.google.com/forum/?fromgroups#!forum/mqtt">MQTT Google Group</a>.</p>
<p>There is much more information available via the <a class="reference external" href="http://mqtt.org/">MQTT community site</a>.</p>
<div class="toctree-wrapper compound">
</div>
</section>
</section>


          </div>
          
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="#">Eclipse paho-mqtt</a></h1>








<h3>Navigation</h3>
<ul>
<li class="toctree-l1"><a class="reference internal" href="client.html">client module</a></li>
<li class="toctree-l1"><a class="reference internal" href="helpers.html">helpers</a></li>
<li class="toctree-l1"><a class="reference internal" href="types.html">Types and enums</a></li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
<li class="toctree-l1"><a class="reference internal" href="migrations.html">Migrations</a></li>
</ul>

<div class="relations">
<h3>Related Topics</h3>
<ul>
  <li><a href="#">Documentation overview</a><ul>
      <li>Next: <a href="client.html" title="next chapter">client module</a></li>
  </ul></li>
</ul>
</div>
<search id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>








        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &#169;2024, Eclipse.
      
      |
      Powered by <a href="https://www.sphinx-doc.org/">Sphinx 7.3.7</a>
      &amp; <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
      
      |
      <a href="_sources/index.rst.txt"
          rel="nofollow">Page source</a>
    </div>

    

    
  </body>
</html>